Object Model

bqplot is based on Grammar of Graphics paradigm. The Object Model in bqplot gives the user the full flexibility to build custom plots. This means the API is verbose but fully customizable.

The following are the steps to build a Figure in bqplot using the Object Model:

Build the scales for x and y quantities using the Scale classes (Scales map the data into pixels in the figure)
Build the marks using the Mark classes. Marks represent the core plotting objects (lines, scatter, bars, pies etc.). Marks take the scale objects created in step 1 as arguments
Build the axes for x and y scales
Finally create a figure using Figure class. Figure takes marks and axes as inputs. Figure object is a widget (it inherits from DOMWidget) and can be rendered like any other jupyter widget

Let's look a simple example to understand these concepts:



In [ ]:

    
from bqplot import (LinearScale, Axis, Figure, OrdinalScale, 
                    LinearScale, Bars, Lines, Scatter)



In [ ]:

    
# first, let's create two vectors x and y to plot using a Lines mark
import numpy as np
x = np.linspace(-10, 10, 100)
y = np.sin(x)

# 1. Create the scales
xs = LinearScale()
ys = LinearScale()

# 2. Create the axes for x and y
xax = Axis(scale=xs, label='X')
yax = Axis(scale=ys, orientation='vertical', label='Y')

# 3. Create a Lines mark by passing in the scales
# note that Lines object is stored in `line` which can be used later to update the plot
line = Lines(x=x, y=y, scales={'x': xs, 'y': ys})

# 4. Create a Figure object by assembling marks and axes
fig = Figure(marks=[line], axes=[xax, yax], title='Simple Line Chart')

# 5. Render the figure using display or just as is
fig

For creating other marks (like scatter, pie, bars, etc.), only step 3 needs to be changed. Lets look a simple example to create a bar chart:



In [ ]:

    
# first, let's create two vectors x and y to plot a bar chart
x = list('ABCDE')
y = np.random.rand(5)

# 1. Create the scales
xs = OrdinalScale() # note the use of ordinal scale to represent categorical data
ys = LinearScale()

# 2. Create the axes for x and y
xax = Axis(scale=xs, label='X', grid_lines='none') # no grid lines needed for x
yax = Axis(scale=ys, orientation='vertical', label='Y', tick_format='.0%') # note the use of tick_format to format ticks

# 3. Create a Bars mark by passing in the scales
# note that Bars object is stored in `bar` object which can be used later to update the plot
bar = Bars(x=x, y=y, scales={'x': xs, 'y': ys}, padding=.2)

# 4. Create a Figure object by assembling marks and axes
Figure(marks=[bar], axes=[xax, yax], title='Simple Bar Chart')

Mutiple marks can be rendered in a figure. It's as easy as passing a list of marks when constructing the Figure object



In [ ]:

    
# first, let's create two vectors x and y
import numpy as np
x = np.linspace(-10, 10, 25)
y = 3 * x + 5
y_noise = y + 10 * np.random.randn(25) # add some random noise to y

# 1. Create the scales
xs = LinearScale()
ys = LinearScale()

# 2. Create the axes for x and y
xax = Axis(scale=xs, label='X')
yax = Axis(scale=ys, orientation='vertical', label='Y')

# 3. Create a Lines and Scatter marks by passing in the scales
# additional attributes (stroke_width, colors etc.) can be passed as attributes to the mark objects as needed
line = Lines(x=x, y=y, scales={'x': xs, 'y': ys}, colors=['green'], stroke_width=3)
scatter = Scatter(x=x, y=y_noise, scales={'x': xs, 'y': ys}, colors=['red'], stroke='black')

# 4. Create a Figure object by assembling marks and axes
# pass both the marks (line and scatter) as a list to the marks attribute
Figure(marks=[line, scatter], axes=[xax, yax], title='Scatter and Line')

This introduction should be sufficient to get started with the Object Model. For detailed examples of rendering individual marks (with all their attributes) please look at the Object Model examples